proctool_info ProCtool ProCtool is a tool for monitoring and controlling processes on a system. It is available on Solaris only. Proctool is available in binary form for free. It may also be freely distributed within and outside of Sun Microsystems. It is not an official Sun Microsystems product, and it carries no implied support or endorsement from Sun Microsystems. Please do not attempt to log proctool support calls with the Sun Answer Center. The authors, however, intend to support this product on their own time and we encourage you to file bug reports, requests for enhancements and/or comments with us at: morgan.herrington@west.sun.com (Morgan Herrington) and walter.nielsen@eng.sun.com (Walter Nielsen) We will announce new versions of proctool outside of Sun on the newsgroup "comp.unix.solaris", however, we will also maintain a separate "notification" alias which we will use to inform interested users about new releases of the tool. If you would like to be added, just send a short email giving us permission to add you (along with your preferred email address). We intend to keep the latest version(s) of proctool (with documentation, help and startup files) available to the general internet, via anonymous ftp from: sunsite.unc.edu:/pub/sun-info/mde/proctool/proctool_X.Y.tar.Z and available within Sun at: newstop.ebay:/sun/MDE/Performance/proctool/proctool_X.Y.tar.Z (where X.Y is replaced by the appropriate Solaris version number). Proctool sometimes appears on other servers, however, these other locations are not maintained by the authors. If you would like to verify that the binaries you download have not been tampered with, please contact the authors and ask for checksums using "sum" or "md5" (whichever you prefer). We have chosen not to release source for proctool. We feel this reduces our support burden and simplifies our relationship with Sun. Please contact us directly for any special situations. FAQ: --- Q: I applied some patches to my Solaris kernel, now ProCtool won't run. A: ProCtool uses the uname() call to check with OS version is running on. Some patches change the value uname() returns. To override this, use the -v option to ProCtool. Note that ProCtool version 2.X runs only on Solaris version 2.X. Q: What does the following error message mean? Insufficient space for process information; use "-p MaxNumOfProcesses" option A: Proctool currently initializes with some fixed sized tables, including one to hold information for all active processes. The defaults should be large enough for *most* users, however, if you are running a large server you can use the "-p" option to specify an upper bound on the number of processes that you expect. For example: proctool -p 1000 Q: How do I change the default background color in Proctool ? A: Through your X defaults file. The easiest way is to add an entry in your $HOME/.Xdefaults file which looks like this: proctool.*.background: grey # or some other color Q: How do I change the default colors used in the various graphs ? A: Currently ProCtool allocates only 8 colors for the graphs. By default, it would look like this in a X resource file. To change it, make the necessary modifications: proctool.graph_color_1: green proctool.graph_color_2: blue proctool.graph_color_3: yellow proctool.graph_color_4: red proctool.graph_color_5: purple proctool.graph_color_6: orange proctool.graph_color_7: aquamarine proctool.graph_color_8: magenta Q: Do you support non-OpenWindow environments ? A: Proctool is written using Motif under OpenWindows. It requires the Motif library libXm.so.3 under either /usr/dt/lib or /opt/SUNWmotif/lib. ICCCM compliant and is known to work under olwm, olvwm, mwm, and oswm. But the authors do have not the resources to test or support under other X environments or window managers. Q: How do I file a bug ? A: Send a bug report to the authors with as much detail as possible. In all cases, we would need to know at least the architecture (Sparc/Intel), the Solaris version, any kernel patches that have been applied, the number of CPUs. When possible, please try to include a set of commands which reproduces the problem. Even more helpful would be a core file or a traceback from dbx or adb. Q: Can I get sources to ProCtool ? A: We are not distributing sources to ProCtool. * proctool_win ProCtool ProCtool is a tool for monitoring and controlling processes on a system. Most windows within Proctool has a help panel associated with it. More detailed help can be found in the User's manual. The main window is split into three main panes, the Control Area, the Process Area, and the System Area. The Control area (on top) contains control and status information for proctool. The Process Area is a list of processes similar to "ps(1)" output which are selectable with the mouse button. (When a process is selected, a window of detailed, process-specific information is displayed.) The System Area (on the bottom) contains system-wide information along with with a per-CPU information line. This area is also mouse selectable to view in-depth system statistics. The buttons on top of the main window control ProCtool in the following manner: FILE - Show the transcript file, turn on data logging, and save current ProCtool state into a startup file. VIEW - Change the display characteristics of proctool. COMMANDS - Manipulate the state of the current processes. GRAPH - Graph system or process behavior. PROPERTIES - Set properties for the tool, or display process or system properties. * log_win Data Log Property Window The Data Log Property Window allows the user to log the state of the system and processes into a file for future analysis. The file is in ASCII format and written in a way that allows for easy text manipulation via awk/sed/perl. You can log system characteristics, a set of selected variables for up to 8 processes, or some very detailed characteristics of one process. Keep in mind, that certain operations such as Process Backtrace is very time consuming so that a very low sampling periods should be avoided. * monitor_win Monitor Window A monitor is a user definable 'event' that triggers the execution of user definable actions. A monitor consists of an logical expression and a set of actions. When an active monitor is defined, it will apply the monitors expression against the data. For every process expression which evaluates to true, the associated action is performed. (Note that monitors are evaluated in the same order as they are in the Monitor window. This means that the last active monitor will take precedence when conflicting visual actions are specified.) To create a monitor, enter an expression in the Expression input line and a select a set of actions in Action pane. All monitors must be named and entered into the list of available monitors. This is done by selecting the INSERT button near the center of the window. A monitor expression is a logical expression constructed from relational operators, constants, and predefined variables. The predefined variables are the various fields from the process window along with some special system wide variables. Values may be integer, hexadecimal, floating point, or string values. When a monitor is active, its expression is applied against each process. The evaluation occurs when a new active monitor is defined and every time a new sample is taken. (Only those monitors which are active will be evaluated; active monitors are shown with a leading asterisk.) Monitors can generate a number of predefined or user defined actions. Two of the simplest are the "Visual" and "Hide" actions which cause the entry for a process to change color or disappear, respectively. The "Beep" action generates an audible bell when the monitor is triggered. The "Popup" action will cause a popup window to appear which will show the process id's of the first ten processes that triggered the monitor. (The remaining processes can be seen in the transcript.) A more complicated action is "Mail" which sends mail when the monitor expression evaluates true. By default, the mail is sent to the person running proctool with a short message stating the command, process id and monitor expression which generated the action. You also have the ability, via the "Edit Mail Template" button to customize the standard template. See "Help" under the "Compose Mail" window for more information. The most general action is "Command" which invokes an arbitrary shell command, after expanding predefined variables like $USER, $CMD, and $PID to their actual values from the process which triggered the monitor. NOTE: The current version of proctool will hang until the generated command is completed. Monitors by default trigger for an indefinite period of time once they are activated. This "Monitor State" toggle allows the user to change that behavior. Selecting ONCE implies that the monitor will trigger exactly once and then deactivate itself. * tool_prop_win Tool Properties This property window allows the user to set properties associated with ProCtool. Auto Update toggles whether the process window will automatically be updated after a Proctool-invoked command. If this feature is turned on, the process window is updated after say a "Kill process" command. This has the affect of keeping the process window in sync with the state of the processes when issuing a lot of commands. You may also select whether the transcript file will be appended to an existing transcript or will instead overwrite an existing file on startup (via "Transcript Mode). The name of the transcript filename may be changed. The change takes place immediately. In order for this change to take affect on the next invocation of Proctool, you will need to save the current state. * sort_win Sort Window This window allows the user to specify what fields to use to sort the processes visible in the process window. To specify a sort, select one or more variables (fields) to be used as sort keys. Multiple key sorts are allowed with up to 20 keys. By default, ProCtool sorts in ascending order. To sort in descending order, select "Sort Descending" before selecting the sort key. Descending sort keys are denoted with a leading '~' character. * viewpoint_win Viewpoint Window This window allows the user to select which process fields are to be displayed in the process window. To create a viewpoint, select a set of variables and "Apply" them. Viewpoints can be saved for later selection by assigning a name under "Viewpoint Name" and inserting it into the viewpoint database. You may later re-select this viewpoint and "Apply" it. * mail_win Compose Mail This window allows you to customize a mail message to be sent by proctool when a monitor is triggered. All predefined variables, like $USER, $CMD, $PID, $RSS, $CPU, etc will be expanded to the actual values from the process which triggered the monitor. To customize the mail message, just edit the "Compose Mail" popup window. The edited template now becomes associated with the action for this particular monitor. All other unedited monitor mail templates are not affected. * priocntl_win Process Control Window This window controls process binding and priority. The first menu, "Bind to Processor #" allows you to select a set of processes (via the selection mechanism in the main display) and bind them to a particular processor (or alternatively, to unbind them). Note that this does not inhibit other processes from migrating to this processor, however, it does keep the selected processes from migrating away. The second menu, "Change Priority To" allows you to control the scheduling class (and parameters) of one or more processes. Under the "Time-Share" selection, you can set the Time-Sharing Priority and Priority Limit. Under "Real-Time", you can set the Real-Time Priority, Time Quanta, and Time Resolution. Users without root privileges may change the priority of only their processes. * signal_win Signal Command Window This command window allows the user to send a selected signal to all processes selected in the main ProCtool process window. The user must be running in privileged mode in order to send a signal to a process running under an effective user ID other than their own. * cpucntl_win Processor Command Window This window allows you to disable or enable particular processors. Note that you are not allowed to disable ALL processors simultaneously, and you must have "root" privileges to successfully execute this operation. * process_win Process Detail Window This window allows you to look a some very detailed information about a process. The information provided here is not shown in the main process window since it is typically very expensive to do for all the processes. Unless you have "root" privileges, you cannot use this window on another user's process. Turning on the Auto-Update mode make this window refresh its data at the same sampling period as the main process window. The Update Once button does this as a one-shot event. For multi-threaded programs, the LWP window lets you select which LWP you want look at. The LWP selection is turned on only for the Traceback, Resources, and I/O selections. The other selections apply to the process as a whole, and not to any individual LWP. * system_win System Detail Window This window gives some detailed information regarding the system as a whole. Turning on the Auto-Update mode make this window refresh its data at the same sampling period as the main process window. The Update Once button does this as a one-shot event. The Hardware Configuration window is not very interesting right now but expect that to be enhanced in some future release. Also, unfortunately the I/O statistics are not synchronized with the I/O graphs right now. That will be fixed in some future release as well. *